docs: add @remarks to EnvironmentManager interface documenting when each method is called#1437
Open
StellaHuang95 wants to merge 4 commits intomicrosoft:mainfrom
Open
docs: add @remarks to EnvironmentManager interface documenting when each method is called#1437StellaHuang95 wants to merge 4 commits intomicrosoft:mainfrom
StellaHuang95 wants to merge 4 commits intomicrosoft:mainfrom
Conversation
Member
|
will review - sorry for the delay |
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds @remarks documentation to the EnvironmentManager interface to clarify which user actions / internal events trigger each method, helping third-party implementers understand lifecycle and call frequency.
Changes:
- Added
@remarkssections for 8EnvironmentManagermethods describing triggering UI actions and internal flows. - Mirrored the same documentation in both the internal (
src/api.ts) and published (pythonEnvironmentsApi/src/main.ts) API surfaces.
Show a summary per file
| File | Description |
|---|---|
| src/api.ts | Adds @remarks to EnvironmentManager methods documenting when each is invoked. |
| pythonEnvironmentsApi/src/main.ts | Mirrors the same @remarks additions for the published API package. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 3
Contributor
Author
|
done addressing the comments |
| * @returns A promise that resolves when the environment is removed. | ||
| * | ||
| * @remarks | ||
| * Called when the user right-clicks an environment in the Python Environments tree view and selects |
Member
There was a problem hiding this comment.
this can also be called by another extension or elsewhere in the extension tho? I am worried about tying these so closely to their current implementations they will become stale quickly and then lead future agents astray
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
@remarksJSDoc sections to all methods on theEnvironmentManagerinterface, documenting which user actions or internal events trigger each method. Changes are documentation-only — no functional changes.Motivation
Raised in #378: third-party extension authors implementing
EnvironmentManagerknow what each method does (the existing JSDoc covers that), but not when or why it gets called. For example,get()is described as "retrieves the current Python environment" — but there's no mention that it's called at extension startup, during terminal activation, before script execution, etc.This makes it hard for authors to reason about their implementation. They end up guessing at lifecycle behavior, which leads to bugs (e.g., not caching in
get()because they didn't realize it's called frequently).What's added
@remarkssections on 8 methods ofEnvironmentManagerin bothsrc/api.tsandpythonEnvironmentsApi/src/main.ts:createremoverefreshgetEnvironmentsrefreshsetgetset, terminal activation, script execution, picker display, auto-discoveryresolvedefaultInterpreterPathresolution, pre-run resolutionclearCacheEach remark was verified by tracing every call site through
InternalEnvironmentManager→envManagers.ts→envCommands.ts→extension.tscommand registrations andpackage.jsonmenu contributions.Who this helps
Extension authors building environment managers for tools like Hatch, Pixi, uv, etc. They can now hover over any
EnvironmentManagermethod in their IDE and see exactly what user actions will invoke it, making implementation decisions much clearer.Files changed
src/api.ts— internal API copy (+45 lines, documentation only)pythonEnvironmentsApi/src/main.ts— published API package (+45 lines, documentation only)Refs #378